// Licensed to Cloudera, Inc. under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  Cloudera, Inc. licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.cloudera.api.v8;

import com.cloudera.api.model.ApiAuditList;
import com.cloudera.api.v4.AuditsResource;

import javax.ws.rs.Consumes;
import javax.ws.rs.DefaultValue;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;

import static com.cloudera.api.Parameters.DATE_TIME_NOW;
import static com.cloudera.api.Parameters.QUERY;

@Consumes({ MediaType.APPLICATION_JSON })
@Produces({ MediaType.APPLICATION_JSON })
public interface AuditsResourceV8 extends AuditsResource {

  /**
   * Fetch audit events from Cloudera Manager (CM) and CM managed services
   * like HDFS, HBase, Impala, Hive, and Sentry.
   * <p>
   * By default, this call will fetch the first 100 audit events (sorted from most
   * recent to oldest) corresponding to a 1 day window based on provided end time
   * (which defaults to the  current CM server time). The <em>startTime</em> and
   * <em>endTime</em> parameters can be used to control the window being queried.
   * <p>
   * Audit events for CM managed services are only retrieved if Cloudera
   * Navigator server is running.
   *
   * @param maxResults Maximum number of audits to return
   * @param resultOffset Offset of audits to return
   * @param startTime Start of the period to query in ISO 8601 format (defaults
   * to 1 day ago relative to endTime).
   * @param endTime End of the period to query in ISO 8601 format (defaults to
   * current time).
   * @param query
   *    The query to filter out audits in the system. It accepts
   *    querying the intersection of a list of constraints,
   *    joined together with semicolons (without spaces). For example:
   *    </p>
   *    <dl>
   *      <dt>command==listStatus</dt>
   *      <dd>looks for audits with listStatus command.</dd>
   *      <dt>command==listStatus;username!=foo</dt>
   *      <dd>looks for audits with listStatus command but excludes
   *      audits generated by foo username</dd>
   *      <dt>command==listStatus;source==*oozie*</dt>
   *      <dd>looks for audits with listStatus command and source that
   *          contains the string 'oozie'.
   *      </dd>
   *    </dl>
   *
   *    Following are valid selectors for the query (if applicable to the
   *    audit):
   *    <table>
   *      <tr>
   *        <th> Selector </th>
   *        <th> Description </th>
   *        <th> SCM </th>
   *        <th> HDFS </th>
   *        <th> HBase </th>
   *        <th> Hive </th>
   *        <th> Impala </th>
   *        <th> Sentry </th>
   *      </tr>
   *      <tr>
   *        <td> service </td>
   *        <td> Cloudera Manager Service </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *      </tr>
   *      <tr>
   *        <td> operation </td>
   *        <td> Operation name </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *      </tr>
   *      <tr>
   *        <td> username </td>
   *        <td> User name </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *      </tr>
   *      <tr>
   *        <td> impersonator</td>
   *        <td> Impersonator </td>
   *        <td> </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *      </tr>
   *      <tr>
   *        <td> ip_address </td>
   *        <td> IP Address </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *      </tr>
   *      <tr>
   *        <td> allowed </td>
   *        <td> Whether the request was allowed or denied </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *      </tr>
   *      <tr>
   *        <td> qualifier</td>
   *        <td> Column qualifier </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> x </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *      </tr>
   *      <tr>
   *        <td> source </td>
   *        <td> Source resource of the operation  </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> </td>
   *      </tr>
   *      <tr>
   *        <td> destination </td>
   *        <td> Destination resource of the operation </td>
   *        <td> </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> </td>
   *      </tr>
   *      <tr>
   *        <td> hostIpAddress </td>
   *        <td> Host IP Address </td>
   *        <td> x </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *      </tr>
   *      <tr>
   *        <td> role </td>
   *        <td> Cloudera Manager Role </td>
   *        <td> x </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *      </tr>
   *      <tr>
   *        <td> family </td>
   *        <td> Column family </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> x </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *      </tr>
   *      <tr>
   *        <td> database_name </td>
   *        <td> Database name </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *      </tr>
   *      <tr>
   *        <td> table_name </td>
   *        <td> Table name </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *      </tr>
   *      <tr>
   *        <td> object_type </td>
   *        <td> Type of object being handled </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *      </tr>
   *      <tr>
   *        <td> operation_text </td>
   *        <td> Command/query text </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> </td>
   *        <td> x </td>
   *        <td> x </td>
   *        <td> x </td>
   *      </tr>
   *    </table>
   *    <p>
   *    The only supported operator is <em>";"</em> (Boolean AND). Boolean OR is
   *    not supported.
   *    <p>
   *    The supported comparators are <em>==</em> and <em>!=</em>
   *    Note that "LIKE" comparison is supported using the wild card syntax,
   *    for example <em>foo==*value*</em>. Asterisk is interpreted as a wild
   *    card character and must not be part of the value. (LIKE comparison
   *    queries are converted to standard SQL LIKE syntax, so any % (%25)
   *    character in a value that also contains a wild card will be
   *    interpreted as a wild card.)
   * <p/>
   * Available since API v8. A subset of these features is available since v4.
   *
   * @return List of audits in descending order of timestamp
   */
  @Override
  @GET
  @Path("/")
  public ApiAuditList readAudits(
      @QueryParam(value = "maxResults")
      @DefaultValue("100") Integer maxResults,
      @QueryParam(value = "resultOffset")
      @DefaultValue("0") Integer resultOffset,
      @QueryParam("startTime")
      String startTime,
      @QueryParam("endTime")
      @DefaultValue(DATE_TIME_NOW)
      String endTime,
      @QueryParam(QUERY) String query);

}
